home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / gnu / amiga / gcc233.lha / info / termcap-2 < prev    next >
Text File  |  1991-01-10  |  44KB  |  1,031 lines

  1. Info file ../info/termcap, produced by Makeinfo, -*- Text -*- from
  2. input file termcap.texinfo.
  3.  
  4. This file documents the termcap library of the GNU system.
  5.  
  6. Copyright (C) 1988 Free Software Foundation, Inc.
  7.  
  8. Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12. Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.  
  17. Permission is granted to copy and distribute translations of this
  18. manual into another language, under the above conditions for modified
  19. versions, except that this permission notice may be stated in a
  20. translation approved by the Foundation.
  21.  
  22.  
  23. 
  24. File: termcap,  Node: Capabilities,  Next: Summary,  Prev: Data Base,  Up: Top
  25.  
  26. Definitions of the Terminal Capabilities
  27. ****************************************
  28.  
  29. This section is divided into many subsections, each for one aspect of
  30. use of display terminals.  For writing a display program, you usually
  31. need only check the subsections for the operations you want to use. 
  32. For writing a terminal description, you must read each subsection and
  33. fill in the capabilities described there.
  34.  
  35. String capabilities that are display commands may require numeric
  36. parameters (*note Parameters::.).  Most such capabilities do not use
  37. parameters.  When a capability requires parameters, this is
  38. explicitly stated at the beginning of its definition.  In simple
  39. cases, the first or second sentence of the definition mentions all
  40. the parameters, in the order they should be given, using a name
  41.  
  42. in upper case
  43.  
  44. for each one.  For example, the `rp' capability is a command that
  45. requires two parameters; its definition begins as follows:
  46.  
  47.      String of commands to output a graphic character C, repeated N
  48.      times.
  49.  
  50. In complex cases or when there are many parameters, they are
  51. described explicitly.
  52.  
  53. When a capability is described as obsolete, this means that programs
  54. should not be written to look for it, but terminal descriptions
  55. should still be written to provide it.
  56.  
  57. When a capability is described as very obsolete, this means that it
  58. should be omitted from terminal descriptions as well.
  59.  
  60. * Menu:
  61.  
  62. * Basic::             Basic characteristics.
  63. * Screen Size::       Screen size, and what happens when it changes.
  64. * Cursor Motion::     Various ways to move the cursor.
  65. * Scrolling::         Pushing text up and down on the screen.
  66. * Wrapping::          What happens if you write a character in the last column.
  67. * Windows::           Limiting the part of the window that output affects.
  68. * Clearing::          Erasing one or many lines.
  69. * Insdel Line::       Making new blank lines in mid-screen; deleting lines.
  70. * Insdel Char::       Inserting and deleting characters within a line.
  71. * Standout::          Highlighting some of the text.
  72. * Underlining::       Underlining some of the text.
  73. * Cursor Visibility:: Making the cursor more or less easy to spot.
  74. * Bell::              Attracts user's attention; not localized on the screen.
  75. * Keypad::            Recognizing when function keys or arrows are typed.
  76. * Meta Key::          META acts like an extra shift key.
  77. * Initialization::    Commands used to initialize or reset the terminal.
  78. * Pad Specs::         Info for the kernel on how much padding is needed.
  79. * Status Line::       A status line displays "background" information.
  80. * Half-Line::         Moving by half-lines, for superscripts and subscripts.
  81. * Printer::           Controlling auxiliary printers of display terminals.
  82.  
  83.  
  84. 
  85. File: termcap,  Node: Basic,  Next: Screen Size,  Prev: Capabilities,  Up: Capabilities
  86.  
  87. Basic Characteristics
  88. =====================
  89.  
  90. This section documents the capabilities that describe the basic and
  91. nature of the terminal, and also those that are relevant to the
  92. output of graphic characters.
  93.  
  94. `os'
  95.      Flag whose presence means that the terminal can overstrike. 
  96.      This means that outputting a graphic character does not erase
  97.      whatever was present in the same character position before.  The
  98.      terminals that can overstrike include printing terminals,
  99.      storage tubes (all obsolete nowadays), and many bit-map displays.
  100.  
  101. `eo'
  102.      Flag whose presence means that outputting a space can erase an
  103.      overstrike.  If this is not present and overstriking is
  104.      supported, output of a space has no effect except to move the
  105.      cursor.
  106.  
  107. `gn'
  108.      Flag whose presence means that this terminal type is a generic
  109.      type which does not really describe any particular terminal. 
  110.      Generic types are intended for use as the default type assigned
  111.      when the user connects to the system, with the intention that
  112.      the user should specify what type he really has.  One example of
  113.      a generic type is the type `network'.
  114.  
  115.      Since the generic type cannot say how to do anything interesting
  116.      with the terminal, termcap-using programs will always find that
  117.      the terminal is too weak to be supported if the user has failed
  118.      to specify a real terminal type in place of the generic one. 
  119.      The `gn' flag directs these programs to use a different error
  120.      message: "You have not specified your real terminal type",
  121.      rather than "Your terminal is not powerful enough to be used".
  122.  
  123. `hc'
  124.      Flag whose presence means this is a hardcopy terminal.
  125.  
  126. `rp'
  127.      String of commands to output a graphic character C, repeated N
  128.      times.  The first parameter value is the ASCII code for the
  129.      desired character, and the second parameter is the number of
  130.      times to repeat the character.  Often this command requires
  131.      padding proportional to the  number of times the character is
  132.      repeated.  This effect can be had by using parameter arithmetic
  133.      with `%'-sequences to compute the amount of padding, then
  134.      generating the result as a number at the front of the string so
  135.      that `tputs' will treat it as padding.
  136.  
  137. `hz'
  138.      Flag whose presence means that the ASCII character `~' cannot be
  139.      output on this terminal because it is used for display commands.
  140.  
  141.      Programs handle this flag by checking all text to be output and
  142.      replacing each `~' with some other character(s).  If this is not
  143.      done, the screen will be thoroughly garbled.
  144.  
  145.      The old Hazeltine terminals that required such treatment are
  146.      probably very rare today, so you might as well not bother to
  147.      support this flag.
  148.  
  149. `CC'
  150.      String whose presence means the terminal has a settable command
  151.      character.  The value of the string is the default command
  152.      character (which is usually ESC).
  153.  
  154.      All the strings of commands in the terminal description should
  155.      be written to use the default command character.  If you are
  156.      writing an application program that changes the command
  157.      character, use the `CC' capability to figure out how to
  158.      translate all the display commands to work with the new command
  159.      character.
  160.  
  161.      Most programs have no reason to look at the `CC' capability.
  162.  
  163. `xb'
  164.      Flag whose presence identifies Superbee terminals which are
  165.      unable to transmit the characters ESC and `Control-C'.  Programs
  166.      which support this flag are supposed to check the input for the
  167.      code sequences sent by the F1 and F2 keys, and pretend that ESC
  168.      or `Control-C' (respectively) had been read.  But this flag is
  169.      obsolete, and not worth supporting.
  170.  
  171.  
  172. 
  173. File: termcap,  Node: Screen Size,  Next: Cursor Motion,  Prev: Basic,  Up: Capabilities
  174.  
  175. Screen Size
  176. ===========
  177.  
  178. A terminal description has two capabilities, `co' and `li', that
  179. describe the screen size in columns and lines.  But there is more to
  180. the question of screen size than this.
  181.  
  182. On some operating systems the "screen" is really a window and the
  183. effective width can vary.  On some of these systems, `tgetnum' uses
  184. the actual width of the window to decide what value to return for the
  185. `co' capability, overriding what is actually written in the terminal
  186. description.  On other systems, it is up to the application program
  187. to check the actual window width using a system call.  For example,
  188. on BSD 4.3 systems, the system call `ioctl' with code `TIOCGWINSZ'
  189. will tell you the current screen size.
  190.  
  191. On all window systems, termcap is powerless to advise the application
  192. program if the user resizes the window.  Application programs must
  193. deal with this possibility in a system-dependent fashion.  On some
  194. systems the C shell handles part of the problem by detecting changes
  195. in window size and setting the `TERMCAP' environment variable
  196. appropriately.  This takes care of application programs that are
  197. started subsequently.  It does not help application programs already
  198. running.
  199.  
  200. On some systems, including BSD 4.3, all programs using a terminal get
  201. a signal named `SIGWINCH' whenever the screen size changes.  Programs
  202. that use termcap should handle this signal by using `ioctl
  203. TIOCGWINSZ' to learn the new screen size.
  204.  
  205. `co'
  206.      Numeric value, the width of the screen in character positions. 
  207.      Even hardcopy terminals normally have a `co' capability.
  208.  
  209. `li'
  210.      Numeric value, the height of the screen in lines.
  211.  
  212.  
  213. 
  214. File: termcap,  Node: Cursor Motion,  Next: Wrapping,  Prev: Screen Size,  Up: Capabilities
  215.  
  216. Cursor Motion
  217. =============
  218.  
  219. Termcap assumes that the terminal has a "cursor", a spot on the
  220. screen where a visible mark is displayed, and that most display
  221. commands take effect at the position of the cursor.  It follows that
  222. moving the cursor to a specified location is very important.
  223.  
  224. There are many terminal capabilities for different cursor motion
  225. operations.  A terminal description should define as many as
  226. possible, but most programs do not need to use most of them.  One
  227. capability, `cm', moves the cursor to an arbitrary place on the
  228. screen; this by itself is sufficient for any application as long as
  229. there is no need to support hardcopy terminals or certain old, weak
  230. displays that have only relative motion commands.  Use of other
  231. cursor motion capabilities is an optimization, enabling the program
  232. to output fewer characters in some common cases.
  233.  
  234. If you plan to use the relative cursor motion commands in an
  235. application program, you must know what the starting cursor position
  236. is.  To do this, you must keep track of the cursor position and
  237. update the records each time anything is output to the terminal,
  238. including graphic characters.  In addition, it is necessary to know
  239. whether the terminal wraps after writing in the rightmost column. 
  240. *Note Wrapping::.
  241.  
  242. One other motion capability needs special mention: `nw' moves the
  243. cursor to the beginning of the following line, perhaps clearing all
  244. the starting line after the cursor, or perhaps not clearing at all. 
  245. This capability is a least common denominator that is probably
  246. supported even by terminals that cannot do most other things such as
  247. `cm' or `do'.  Even hardcopy terminals can support `nw'.
  248.  
  249. `cm'
  250.      String of commands to position the cursor at line L, column C. 
  251.      Both parameters are origin-zero, and are defined relative to the
  252.      screen, not relative to display memory.
  253.  
  254.      All display terminals except a few very obsolete ones support
  255.      `cm', so it is acceptable for an application program to refuse
  256.      to operate on terminals lacking `cm'.
  257.  
  258. `ho'
  259.      String of commands to move the cursor to the upper left corner
  260.      of the screen (this position is called the "home position").  In
  261.      terminals where the upper left corner of the screen is not the
  262.      same as the beginning of display memory, this command must go to
  263.      the upper left corner of the screen, not the beginning of
  264.      display memory.
  265.  
  266.      Every display terminal supports this capability, and many
  267.      application programs refuse to operate if the `ho' capability is
  268.      missing.
  269.  
  270. `ll'
  271.      String of commands to move the cursor to the lower left corner
  272.      of the screen.  On some terminals, moving up from home position
  273.      does this, but programs should never assume that will work. 
  274.      Just output the `ll' string (if it is provided); if moving to
  275.      home position and then moving up is the best way to get there,
  276.      the `ll' command will do that.
  277.  
  278. `cr'
  279.      String of commands to move the cursor to the beginning of the
  280.      line it is on.  If this capability is not specified, many
  281.      programs assume they can use the ASCII carriage return character
  282.      for this.
  283.  
  284. `le'
  285.      String of commands to move the cursor left one column.  Unless
  286.      the `bw' flag capability is specified, the effect is undefined
  287.      if the cursor is at the left margin; do not use this command
  288.      there.  If `bw' is present, this command may be used at the left
  289.      margin, and it wraps the cursor to the last column of the
  290.      preceding line.
  291.  
  292. `nd'
  293.      String of commands to move the cursor right one column.  The
  294.      effect is undefined if the cursor is at the right margin; do not
  295.      use this command there, not even if `am' is present.
  296.  
  297. `up'
  298.      String of commands to move the cursor vertically up one line. 
  299.      The effect of sending this string when on the top line is
  300.      undefined; programs should never use it that way.
  301.  
  302. `do'
  303.      String of commands to move the cursor vertically down one line. 
  304.      The effect of sending this string when on the bottom line is
  305.      undefined; programs should never use it that way.
  306.  
  307.      The original idea was that this string would not contain a
  308.      newline character and therefore could be used without disabling
  309.      the kernel's usual habit of converting of newline into a
  310.      carriage-return newline sequence.  But many terminal
  311.      descriptions do use newline in the `do' string, so this is not
  312.      possible; a program which sends the `do' string must disable
  313.      output conversion in the kernel (*note Initialize::.).
  314.  
  315. `bw'
  316.      Flag whose presence says that `le' may be used in column zero to
  317.      move to the last column of the preceding line.  If this flag is
  318.      not present, `le' should not be used in column zero.
  319.  
  320. `nw'
  321.      String of commands to move the cursor to start of next line,
  322.      possibly clearing rest of line (following the cursor) before
  323.      moving.
  324.  
  325. `DO', `UP', `LE', `RI'
  326.      Strings of commands to move the cursor N lines down vertically,
  327.      up vertically, or N columns left or right.  Do not attempt to
  328.      move past any edge of the screen with these commands; the effect
  329.      of trying that is undefined.  Only a few terminal descriptions
  330.      provide these commands, and most programs do not use them.
  331.  
  332. `CM'
  333.      String of commands to position the cursor at line L, column C,
  334.      relative to display memory.  Both parameters are origin-zero. 
  335.      This capability is present only in terminals where there is a
  336.      difference between screen-relative and memory-relative
  337.      addressing, and not even in all such terminals.
  338.  
  339. `ch'
  340.      String of commands to position the cursor at column C in the
  341.      same line it is on.  This is a special case of `cm' in which the
  342.      vertical position is not changed.  The `ch' capability is
  343.      provided only when it is faster to output than `cm' would be in
  344.      this special case.  Programs should not assume most display
  345.      terminals have `ch'.
  346.  
  347. `cv'
  348.      String of commands to position the cursor at line L in the same
  349.      column.  This is a special case of `cm' in which the horizontal
  350.      position is not changed.  The `cv' capability is provided only
  351.      when it is faster to output than `cm' would be in this special
  352.      case.  Programs should not assume most display terminals have
  353.      `cv'.
  354.  
  355. `sc'
  356.      String of commands to make the terminal save the current cursor
  357.      position.  Only the last saved position can be used.  If this
  358.      capability is present, `rc' should be provided also.  Most
  359.      terminals have neither.
  360.  
  361. `rc'
  362.      String of commands to make the terminal restore the last saved
  363.      cursor position.  If this capability is present, `sc' should be
  364.      provided also.  Most terminals have neither.
  365.  
  366. `ff'
  367.      String of commands to advance to the next page, for a hardcopy
  368.      terminal.
  369.  
  370. `ta'
  371.      String of commands to move the cursor right to the next hardware
  372.      tab stop column.  Missing if the terminal does not have any kind
  373.      of hardware tabs.  Do not send this command if the kernel's
  374.      terminal modes say that the kernel is expanding tabs into spaces.
  375.  
  376. `bt'
  377.      String of commands to move the cursor left to the previous
  378.      hardware tab stop column.  Missing if the terminal has no such
  379.      ability; many terminals do not.  Do not send this command if the
  380.      kernel's terminal modes say that the kernel is expanding tabs
  381.      into spaces.
  382.  
  383. The following obsolete capabilities should be included in terminal
  384. descriptions when appropriate, but should not be looked at by new
  385. programs.
  386.  
  387. `nc'
  388.      Flag whose presence means the terminal does not support the
  389.      ASCII carriage return character as `cr'.  This flag is needed
  390.      because old programs assume, when the `cr' capability is
  391.      missing, that ASCII carriage return can be used for the purpose.
  392.      We use `nc' to tell the old programs that carriage return may
  393.      not be used.
  394.  
  395.      New programs should not assume any default for `cr', so they
  396.      need not look at `nc'.  However, descriptions should contain
  397.      `nc' whenever they do not contain `cr'.
  398.  
  399. `xt'
  400.      Flag whose presence means that the ASCII tab character may not
  401.      be used for cursor motion.  This flag exists because old
  402.      programs assume, when the `ta' capability is missing, that ASCII
  403.      tab can be used for the purpose.  We use `xt' to tell the old
  404.      programs not to use tab.
  405.  
  406.      New programs should not assume any default for `ta', so they
  407.      need not look at `xt' in connection with cursor motion.  Note
  408.      that `xt' also has implications for standout mode (*note
  409.      Standout::.).  It is obsolete in regard to cursor motion but not
  410.      in regard to standout.
  411.  
  412.      In fact, `xt' means that the terminal is a Teleray 1061.
  413.  
  414. `bc'
  415.      Very obsolete alternative name for the `le' capability.
  416.  
  417. `bs'
  418.      Flag whose presence means that the ASCII character backspace may
  419.      be used to move the cursor left.  Obsolete; look at `le' instead.
  420.  
  421. `nl'
  422.      Obsolete capability which is a string that can either be used to
  423.      move the cursor down or to scroll.  The same string must scroll
  424.      when used on the bottom line and move the cursor when used on
  425.      any other line.  New programs should use `do' or `sf', and
  426.      ignore `nl'.
  427.  
  428.      If there is no `nl' capability, some old programs assume they
  429.      can use the newline character for this purpose.  These programs
  430.      follow a bad practice, but because they exist, it is still
  431.      desirable to define the `nl' capability in a terminal
  432.      description if the best way to move down is *not* a newline.
  433.  
  434.  
  435. 
  436. File: termcap,  Node: Wrapping,  Next: Scrolling,  Prev: Cursor Motion,  Up: Capabilities
  437.  
  438. Wrapping
  439. ========
  440.  
  441. "Wrapping" means moving the cursor from the right margin to the left
  442. margin of the following line.  Some terminals wrap automatically when
  443. a graphic character is output in the last column, while others do
  444. not.  Most application programs that use termcap need to know whether
  445. the terminal wraps.  There are two special flag capabilities to
  446. describe what the terminal does when a graphic character is output in
  447. the last column.
  448.  
  449. `am'
  450.      Flag whose presence means that writing a character in the last
  451.      column causes the cursor to wrap to the beginning of the next
  452.      line.
  453.  
  454.      If `am' is not present, writing in the last column leaves the
  455.      cursor at the place where the character was written.
  456.  
  457.      Writing in the last column of the last line should be avoided on
  458.      terminals with `am', as it may or may not cause scrolling to
  459.      occur (*note Scrolling::.).  Scrolling is surely not what you
  460.      would intend.
  461.  
  462.      If your program needs to check the `am' flag, then it also needs
  463.      to check the `xn' flag which indicates that wrapping happens in
  464.      a strange way.  Many common terminals have the `xn' flag.
  465.  
  466. `xn'
  467.      Flag whose presence means that the cursor wraps in a strange
  468.      way.  At least two distinct kinds of strange behavior are known;
  469.      the termcap data base does not contain anything to distinguish
  470.      the two.
  471.  
  472.      On Concept-100 terminals, output in the last column wraps the
  473.      cursor almost like an ordinary `am' terminal.  But if the next
  474.      thing output is a newline, it is ignored.
  475.  
  476.      DEC VT-100 terminals (when the wrap switch is on) do a different
  477.      strange thing: the cursor wraps only if the next thing output is
  478.      another graphic character.  In fact, the wrap occurs when the
  479.      following graphic character is received by the terminal, before
  480.      the character is placed on the screen.
  481.  
  482.      On both of these terminals, after writing in the last column a
  483.      following graphic character will be displayed in the first
  484.      column of the following line.  But the effect of relative cursor
  485.      motion characters such as newline or backspace at such a time
  486.      depends on the terminal.  The effect of erase or scrolling
  487.      commands also depends on the terminal.  You can't assume
  488.      anything about what they will do on a terminal that has `xn'. 
  489.      So, to be safe, you should never do these things at such a time
  490.      on such a terminal.
  491.  
  492.      To be sure of reliable results on a terminal which has the `xn'
  493.      flag, output a `cm' absolute positioning command after writing
  494.      in the last column.  Another safe thing to do is to output
  495.      carriage-return newline, which will leave the cursor at the
  496.      beginning of the following line.
  497.  
  498.  
  499. 
  500. File: termcap,  Node: Scrolling,  Next: Windows,  Prev: Wrapping,  Up: Capabilities
  501.  
  502. Scrolling
  503. =========
  504.  
  505. "Scrolling" means moving the contents of the screen up or down one or
  506. more lines.  Moving the contents up is "forward scrolling"; moving
  507. them down is "reverse scrolling".
  508.  
  509. Scrolling happens after each line of output during ordinary output on
  510. most display terminals.  But in an application program that uses
  511. termcap for random-access output, scrolling happens only when
  512. explicitly requested with the commands in this section.
  513.  
  514. Some terminals have a "scroll region" feature.  This lets you limit
  515. the effect of scrolling to a specified range of lines.  Lines outside
  516. the range are unaffected when scrolling happens.  The scroll region
  517. feature is available if either `cs' or `cS' is present.
  518.  
  519. `sf'
  520.      String of commands to scroll the screen one line up, assuming it
  521.      is output with the cursor at the beginning of the bottom line.
  522.  
  523. `sr'
  524.      String of commands to scroll the screen one line down, assuming
  525.      it is output with the cursor at the beginning of the top line.
  526.  
  527. `SF'
  528.      String of commands to scroll the screen N lines up, assuming it
  529.      is output with the cursor at the beginning of the bottom line.
  530.  
  531. `SR'
  532.      String of commands to scroll the screen N line down, assuming it
  533.      is output with the cursor at the beginning of the top line.
  534.  
  535. `cs'
  536.      String of commands to set the scroll region.  This command takes
  537.      two parameters, START and END, which are the line numbers
  538.      (origin-zero) of the first line to include in the scroll region
  539.      and of the last line to include in it.  When a scroll region is
  540.      set, scrolling is limited to the specified range of lines; lines
  541.      outside the range are not affected by scroll commands.
  542.  
  543.      Do not try to move the cursor outside the scroll region.  The
  544.      region remains set until explicitly removed.  To remove the
  545.      scroll region, use another `cs' command specifying the full
  546.      height of the screen.
  547.  
  548.      The cursor position is undefined after the `cs' command is set,
  549.      so position the cursor with `cm' immediately afterward.
  550.  
  551. `cS'
  552.      String of commands to set the scroll region using parameters in
  553.      different form.  The effect is the same as if `cs' were used. 
  554.      Four parameters are required:
  555.  
  556.        1. Total number of lines on the screen.
  557.  
  558.        2. Number of lines above desired scroll region.
  559.  
  560.        3. Number of lines below (outside of) desired scroll region.
  561.  
  562.        4. Total number of lines on the screen, the same as the first
  563.           parameter.
  564.  
  565.      This capability is a GNU extension that was invented to allow
  566.      the Ann Arbor Ambassador's scroll-region command to be
  567.      described; it could also be done by putting non-Unix
  568.      `%'-sequences into a `cs' string, but that would have confused
  569.      Unix programs that used the `cs' capability with the Unix
  570.      termcap.  Currently only GNU Emacs uses the `cS' capability.
  571.  
  572. `ns'
  573.      Flag which means that the terminal does not normally scroll for
  574.      ordinary sequential output.  For modern terminals, this means
  575.      that outputting a newline in ordinary sequential output with the
  576.      cursor on the bottom line wraps to the top line.  For some
  577.      obsolete terminals, other things may happen.
  578.  
  579.      The terminal may be able to scroll even if it does not normally
  580.      do so.  If the `sf' capability is provided, it can be used for
  581.      scrolling regardless of `ns'.
  582.  
  583. `da'
  584.      Flag whose presence means that lines scrolled up off the top of
  585.      the screen may come back if scrolling down is done subsequently.
  586.  
  587.      The `da' and `db' flags do not, strictly speaking, affect how to
  588.      scroll.  But programs that scroll usually need to clear the
  589.      lines scrolled onto the screen, if these flags are present.
  590.  
  591. `db'
  592.      Flag whose presence means that lines scrolled down off the
  593.      bottom of the screen may come back if scrolling up is done
  594.      subsequently.
  595.  
  596. `lm'
  597.      Numeric value, the number of lines of display memory that the
  598.      terminal has.  A value of zero means that the terminal has more
  599.      display memory than can fit on the screen, but no fixed number
  600.      of lines.  (The number of lines may depend on the amount of text
  601.      in each line.)
  602.  
  603. Any terminal description that defines `SF' should also define `sf';
  604. likewise for `SR' and `sr'.  However, many terminals can only scroll
  605. by one line at a time, so it is common to find `sf' and not `SF', or
  606. `sr' without `SR'.
  607.  
  608. Therefore, all programs that use the scrolling facilities should be
  609. prepared to work with `sf' in the case that `SF' is absent, and
  610. likewise with `sr'.  On the other hand, an application program that
  611. uses only `sf' and not `SF' is acceptable, though slow on some
  612. terminals.
  613.  
  614. When outputting a scroll command with `tputs', the NLINES argument
  615. should be the total number of lines in the portion of the screen
  616. being scrolled.  Very often these commands require padding
  617. proportional to this number of lines.  *Note Padding::.
  618.  
  619.  
  620. 
  621. File: termcap,  Node: Windows,  Next: Clearing,  Prev: Scrolling,  Up: Capabilities
  622.  
  623. Windows
  624. =======
  625.  
  626. A "window", in termcap, is a rectangular portion of the screen to
  627. which all display operations are restricted.  Wrapping, clearing,
  628. scrolling, insertion and deletion all operate as if the specified
  629. window were all the screen there was.
  630.  
  631. `wi'
  632.      String of commands to set the terminal output screen window. 
  633.      This string requires four parameters, all origin-zero:
  634.  
  635.        1. The first line to include in the window.
  636.  
  637.        2. The last line to include in the window.
  638.  
  639.        3. The first column to include in the window.
  640.  
  641.        4. The last column to include in the window.
  642.  
  643. Most terminals do not support windows.
  644.  
  645.  
  646. 
  647. File: termcap,  Node: Clearing,  Next: Insdel Line,  Prev: Windows,  Up: Capabilities
  648.  
  649. Clearing Parts of the Screen
  650. ============================
  651.  
  652. There are several terminal capabilities for clearing parts of the
  653. screen to blank.  All display terminals support the `cl' string, and
  654. most display terminals support all of these capabilities.
  655.  
  656. `cl'
  657.      String of commands to clear the entire screen and position the
  658.      cursor at the upper left corner.
  659.  
  660. `cd'
  661.      String of commands to clear the line the cursor is on, and all
  662.      the lines below it, down to the bottom of the screen.  This
  663.      command string should be used only with the cursor in column
  664.      zero; their effect is undefined if the cursor is elsewhere.
  665.  
  666. `ce'
  667.      String of commands to clear from the cursor to the end of the
  668.      current line.
  669.  
  670. `ec'
  671.      String of commands to clear N characters, starting with the
  672.      character that the cursor is on.  This command string is
  673.      expected to leave the cursor position unchanged.  The parameter
  674.      N should never be large enough to reach past the right margin;
  675.      the effect of such a large parameter would be undefined.
  676.  
  677. Clear to end of line (`ce') is extremely important in programs that
  678. maintain an updating display.  Nearly all display terminals support
  679. this operation, so it is acceptable for a an application program to
  680. refuse to work if `ce' is not present.  However, if you do not want
  681. this limitation, you can accomplish clearing to end of line by
  682. outputting spaces until you reach the right margin.  In order to do
  683. this, you must know the current horizontal position.  Also, this
  684. technique assumes that writing a space will erase.  But this happens
  685. to be true on all the display terminals that fail to support `ce'.
  686.  
  687.  
  688. 
  689. File: termcap,  Node: Insdel Line,  Next: Insdel Char,  Prev: Clearing,  Up: Capabilities
  690.  
  691. Insert/Delete Line
  692. ==================
  693.  
  694. "Inserting a line" means creating a blank line in the middle of the
  695. screen, and pushing the existing lines of text apart.  In fact, the
  696. lines above the insertion point do not change, while the lines below
  697. move down, and one is normally lost at the bottom of the screen.
  698.  
  699. "Deleting a line" means causing the line to disappear from the
  700. screen, closing up the gap by moving the lines below it upward.  A
  701. new line appears at the bottom of the screen.  Usually this line is
  702. blank, but on terminals with the `db' flag it may be a line
  703. previously moved off the screen bottom by scrolling or line insertion.
  704.  
  705. Insertion and deletion of lines is useful in programs that maintain
  706. an updating display some parts of which may get longer or shorter. 
  707. They are also useful in editors for scrolling parts of the screen,
  708. and for redisplaying after lines of text are killed or inserted.
  709.  
  710. Many terminals provide commands to insert or delete a single line at
  711. the cursor position.  Some provide the ability to insert or delete
  712. several lines with one command, using the number of lines to insert
  713. or delete as a parameter.  Always move the cursor to column zero
  714. before using any of these commands.
  715.  
  716. `al'
  717.      String of commands to insert a blank line before the line the
  718.      cursor is on.  The existing line, and all lines below it, are
  719.      moved down.  The last line in the screen (or in the scroll
  720.      region, if one is set) disappears and in most circumstances is
  721.      discarded.  It may not be discarded if the `db' is present
  722.      (*note Scrolling::.).
  723.  
  724.      The cursor must be at the left margin before this command is used.
  725.      This command does not move the cursor.
  726.  
  727. `dl'
  728.      String of commands to delete the line the cursor is on.  The
  729.      following lines move up, and a blank line appears at the bottom
  730.      of the screen (or bottom of the scroll region).  If the terminal
  731.      has the `db' flag, a nonblank line previously pushed off the
  732.      screen bottom may reappear at the bottom.
  733.  
  734.      The cursor must be at the left margin before this command is used.
  735.      This command does not move the cursor.
  736.  
  737. `AL'
  738.      String of commands to insert N blank lines before the line that
  739.      the cursor is on.  It is like `al' repeated N times, except that
  740.      it is as fast as one `al'.
  741.  
  742. `DL'
  743.      String of commands to delete N lines starting with the line that
  744.      the cursor is on.  It is like `dl' repeated N times, except that
  745.      it is as fast as one `dl'.
  746.  
  747. Any terminal description that defines `AL' should also define `al';
  748. likewise for `DL' and `dl'.  However, many terminals can only insert
  749. or delete one line at a time, so it is common to find `al' and not
  750. `AL', or `dl' without `DL'.
  751.  
  752. Therefore, all programs that use the insert and delete facilities
  753. should be prepared to work with `al' in the case that `AL' is absent,
  754. and likewise with `dl'.  On the other hand, it is acceptable to write
  755. an application that uses only `al' and `dl' and does not look for
  756. `AL' or `DL' at all.
  757.  
  758. If a terminal does not support line insertion and deletion directly,
  759. but does support a scroll region, the effect of insertion and
  760. deletion can be obtained with scrolling.  However, it is up to the
  761. individual user program to check for this possibility and use the
  762. scrolling commands to get the desired result.  It is fairly important
  763. to implement this alternate strategy, since it is the only way to get
  764. the effect of line insertion and deletion on the popular VT100
  765. terminal.
  766.  
  767. Insertion and deletion of lines is affected by the scroll region on
  768. terminals that have a settable scroll region.  This is useful when it
  769. is desirable to move any few consecutive lines up or down by a few
  770. lines.  *Note Scrolling::.
  771.  
  772. The line pushed off the bottom of the screen is not lost if the
  773. terminal has the `db' flag capability; instead, it is pushed into
  774. display memory that does not appear on the screen.  This is the same
  775. thing that happens when scrolling pushes a line off the bottom of the
  776. screen.  Either reverse scrolling or deletion of a line can bring the
  777. apparently lost line back onto the bottom of the screen.  If the
  778. terminal has the scroll region feature as well as `db', the
  779. pushed-out line really is lost if a scroll region is in effect.
  780.  
  781. When outputting an insert or delete command with `tputs', the NLINES
  782. argument should be the total number of lines from the cursor to the
  783. bottom of the screen (or scroll region).  Very often these commands
  784. require padding proportional to this number of lines.  *Note Padding::.
  785.  
  786. For `AL' and `DL' the NLINES argument should *not* depend on the
  787. number of lines inserted or deleted; only the total number of lines
  788. affected.  This is because it is just as fast to insert two or N
  789. lines with `AL' as to insert one line with `al'.
  790.  
  791.  
  792. 
  793. File: termcap,  Node: Insdel Char,  Next: Standout,  Prev: Insdel Line,  Up: Capabilities
  794.  
  795. Insert/Delete Character
  796. =======================
  797.  
  798. "Inserting a character" means creating a blank space in the middle of
  799. a line, and pushing the rest of the line rightward.  The character in
  800. the rightmost column is lost.
  801.  
  802. "Deleting a character" means causing the character to disappear from
  803. the screen, closing up the gap by moving the rest of the line
  804. leftward.  A blank space appears in the rightmost column.
  805.  
  806. Insertion and deletion of characters is useful in programs that
  807. maintain an updating display some parts of which may get longer or
  808. shorter.  It is also useful in editors for redisplaying the results
  809. of editing within a line.
  810.  
  811. Many terminals provide commands to insert or delete a single
  812. character at the cursor position.  Some provide the ability to insert
  813. or delete several characters with one command, using the number of
  814. characters to insert or delete as a parameter.
  815.  
  816. Many terminals provide an insert mode in which outputting a graphic
  817. character has the added effect of inserting a position for that
  818. character.  A special command string is used to enter insert mode and
  819. another is used to exit it.  The reason for designing a terminal with
  820. an insert mode rather than an insert command is that inserting
  821. character positions is usually followed by writing characters into
  822. them.  With insert mode, this is as fast as simply writing the
  823. characters, except for the fixed overhead of entering and leaving
  824. insert mode.  However, when the line speed is great enough, padding
  825. may be required for the graphic characters output in insert mode.
  826.  
  827. Some terminals require you to enter insert mode and then output a
  828. special command for each position to be inserted.  Or they may
  829. require special commands to be output before or after each graphic
  830. character to be inserted.
  831.  
  832. Deletion of characters is usually accomplished by a straightforward
  833. command to delete one or several positions; but on some terminals, it
  834. is necessary to enter a special delete mode before using the delete
  835. command, and leave delete mode afterward.  Sometimes delete mode and
  836. insert mode are the same mode.
  837.  
  838. Some terminals make a distinction between character positions in
  839. which a space character has been output and positions which have been
  840. cleared.  On these terminals, the effect of insert or delete
  841. character runs to the first cleared position rather than to the end
  842. of the line.  In fact, the effect may run to more than one line if
  843. there is no cleared position to stop the shift on the first line. 
  844. These terminals are identified by the `in' flag capability.
  845.  
  846. On terminals with the `in' flag, the technique of skipping over
  847. characters that you know were cleared, and then outputting text later
  848. on in the same line, causes later insert and delete character
  849. operations on that line to do nonstandard things.  A program that has
  850. any chance of doing this must check for the `in' flag and must be
  851. careful to write explicit space characters into the intermediate
  852. columns when `in' is present.
  853.  
  854. A plethora of terminal capabilities are needed to describe all of
  855. this complexity.  Here is a list of them all.  Following the list, we
  856. present an algorithm for programs to use to take proper account of
  857. all of these capabilities.
  858.  
  859. `im'
  860.      String of commands to enter insert mode.
  861.  
  862.      If the terminal has no special insert mode, but it can insert
  863.      characters with a special command, `im' should be defined with a
  864.      null value, because the `vi' editor assumes that insertion of a
  865.      character is impossible if `im' is not provided.
  866.  
  867.      New programs should not act like `vi'.  They should pay
  868.      attention to `im' only if it is defined.
  869.  
  870. `ei'
  871.      String of commands to leave insert mode.  This capability must
  872.      be present if `im' is.
  873.  
  874.      On a few old terminals the same string is used to enter and exit
  875.      insert mode.  This string turns insert mode on if it was off,
  876.      and off it it was on.  You can tell these terminals because the
  877.      `ei' string equals the `im' string.  If you want to support
  878.      these terminals, you must always remember accurately whether
  879.      insert mode is in effect.  However, these terminals are
  880.      obsolete, and it is reasonable to refuse to support them.  On
  881.      all modern terminals, you can safely output `ei' at any time to
  882.      ensure that insert mode is turned off.
  883.  
  884. `ic'
  885.      String of commands to insert one character position at the cursor.
  886.      The cursor does not move.
  887.  
  888.      If outputting a graphic character while in insert mode is
  889.      sufficient to insert the character, then the `ic' capability
  890.      should be defined with a null value.
  891.  
  892.      If your terminal offers a choice of ways to insert--either use
  893.      insert mode or use a special command--then define `im' and do
  894.      not define `ic', since this gives the most efficient operation
  895.      when several characters are to be inserted.  *Do not* define
  896.      both strings, for that means that *both* must be used each time
  897.      insertion is done.
  898.  
  899. `ip'
  900.      String of commands to output following an inserted graphic
  901.      character in insert mode.  Often it is used just for a padding
  902.      spec, when padding is needed after an inserted character (*note
  903.      Padding::.).
  904.  
  905. `IC'
  906.      String of commands to insert N character positions at and after
  907.      the cursor.  It has the same effect as repeating the `ic' string
  908.      and a space, N times.
  909.  
  910.      If `IC' is provided, application programs may use it without
  911.      first entering insert mode.
  912.  
  913. `mi'
  914.      Flag whose presence means it is safe to move the cursor while in
  915.      insert mode and assume the terminal remains in insert mode.
  916.  
  917. `in'
  918.      Flag whose presence means that the terminal distinguishes
  919.      between character positions in which space characters have been
  920.      output and positions which have been cleared.
  921.  
  922. An application program can assume that the terminal can do character
  923. insertion if *any one of* the capabilities `IC', `im', `ic' or `ip'
  924. is provided.
  925.  
  926. To insert N blank character positions, move the cursor to the place
  927. to insert them and follow this algorithm:
  928.  
  929.   1. If an `IC' string is provided, output it with parameter N and
  930.      you are finished.  Otherwise (or if you don't want to bother to
  931.      look for an `IC' string) follow the remaining steps.
  932.  
  933.   2. Output the `im' string, if there is one, unless the terminal is
  934.      already in insert mode.
  935.  
  936.   3. Repeat steps 4 through 6, N times.
  937.  
  938.   4. Output the `ic' string if any.
  939.  
  940.   5. Output a space.
  941.  
  942.   6. Output the `ip' string if any.
  943.  
  944.   7. Output the `ei' string, eventually, to exit insert mode.  There
  945.      is no need to do this right away.  If the `mi' flag is present,
  946.      you can move the cursor and the cursor will remain in insert
  947.      mode; then you can do more insertion elsewhere without
  948.      reentering insert mode.
  949.  
  950. To insert N graphic characters, position the cursor and follow this
  951. algorithm:
  952.  
  953.   1. If an `IC' string is provided, output it with parameter N, then
  954.      output the graphic characters, and you are finished.  Otherwise
  955.      (or if you don't want to bother to look for an `IC' string)
  956.      follow the remaining steps.
  957.  
  958.   2. Output the `im' string, if there is one, unless the terminal is
  959.      already in insert mode.
  960.  
  961.   3. For each character to be output, repeat steps 4 through 6.
  962.  
  963.   4. Output the `ic' string if any.
  964.  
  965.   5. Output the next graphic character.
  966.  
  967.   6. Output the `ip' string if any.
  968.  
  969.   7. Output the `ei' string, eventually, to exit insert mode.  There
  970.      is no need to do this right away.  If the `mi' flag is present,
  971.      you can move the cursor and the cursor will remain in insert
  972.      mode; then you can do more insertion elsewhere without
  973.      reentering insert mode.
  974.  
  975. Note that this is not the same as the original Unix termcap
  976. specifications in one respect: it assumes that the `IC' string can be
  977. used without entering insert mode.  This is true as far as I know,
  978. and it allows you be able to avoid entering and leaving insert mode,
  979. and also to be able to avoid the inserted-character padding after the
  980. characters that go into the inserted positions.
  981.  
  982. Deletion of characters is less complicated; deleting one column is
  983. done by outputting the `dc' string.  However, there may be a delete
  984. mode that must be entered with `dm' in order to make `dc' work.
  985.  
  986. `dc'
  987.      String of commands to delete one character position at the
  988.      cursor.  If `dc' is not present, the terminal cannot delete
  989.      characters.
  990.  
  991. `DC'
  992.      String of commands to delete N characters starting at the cursor.
  993.      It has the same effect as repeating the `dc' string N times. 
  994.      Any terminal description that has `DC' also has `dc'.
  995.  
  996. `dm'
  997.      String of commands to enter delete mode.  If not present, there
  998.      is no delete mode, and `dc' can be used at any time (assuming
  999.      there is a `dc').
  1000.  
  1001. `ed'
  1002.      String of commands to exit delete mode.  This must be present if
  1003.      `dm' is.
  1004.  
  1005. To delete N character positions, position the cursor and follow these
  1006. steps:
  1007.  
  1008.   1. If the `DC' string is present, output it with parameter N and
  1009.      you are finished.  Otherwise, follow the remaining steps.
  1010.  
  1011.   2. Output the `dm' string, unless you know the terminal is already
  1012.      in delete mode.
  1013.  
  1014.   3. Output the `dc' string N times.
  1015.  
  1016.   4. Output the `ed' string eventually.  If the flag capability `mi'
  1017.      is present, you can move the cursor and do more deletion without
  1018.      leaving and reentering delete mode.
  1019.  
  1020. As with the `IC' string, we have departed from the original termcap
  1021. specifications by assuming that `DC' works without entering delete
  1022. mode even though `dc' would not.
  1023.  
  1024. If the `dm' and `im' capabilities are both present and have the same
  1025. value, it means that the terminal has one mode for both insertion and
  1026. deletion.  It is useful for a program to know this, because then it
  1027. can do insertions after deletions, or vice versa, without leaving
  1028. insert/delete mode and reentering it.
  1029.  
  1030.  
  1031.